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Firefox OS 

Firefox OS 18 is a new mobile platform developed by Mozilla 19 and its partners. Devices running 
Firefox OS are already available in many countries and will reach even more places by the end 
of 2013. 

Targeted at developing markets, Firefox OS has the mission to bring the next billion people 
online. To achieve this, Firefox OS devices are built to serve as a great first smartphone along 
with competitive pricing. Firefox OS devices should not be compared with high-end smartphones 
such as the Apple iPhone 5S and Samsung Galaxy S4; they are built to be an alternative to feature 
phones so that people using said devices are able to upgrade to a Firefox OS one at an affordable 
cost and receive the full smartphone experience. 

In developing markets such as Brazil and Colombia, smartphones with decent performance are 
generally too expensive for the average consumer. People are able to buy cheap phones, but the 
platforms used in these phones are intended for high-end devices - as such, the phone's hardware 

18 http://www.mozilla.org/firefox/os/ 
19 http://mozilla.org 
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tends to underperform, which leads to a terrible user experience. Firefox OS is specifically 
designed to run on limited hardware while providing a decent user experience. 

Another differentiating factor of Firefox OS is its openness. Consider that the current mainstream 
mobile operating systems are proprietary silos, where each vendor has the privilege to force his 
way on the developers and users regardless of their wishes (remember when Apple tried banning 
languages other than Objective-C from the ITunes App Store?). In those proprietary ecosystems 
you can only distribute your apps on authorized channels - and the vendor usually keeps a 
significant part of the the money from any purchases made on the device. 

Besides locking the developers to proprietary distribution channels, these systems lock you to 
their software development kits (SDKs). If you want to build a native app for both iOS and 
Android using the official toolkits you will need to code one app using Objective-C and another 
with Java respectively. This means that, code-wise, a developer will reuse very little between 
projects (and maybe reuse some media assets). That kind of effort requires that the developer 
learns two languages and build the same software twice. 

Firefox OS differentiates itself by using "HTML5" as the development platform. HTML5 is a 
marketing term used to mean the ever-evolving collection of Web standards known as HTML, 
CSS and JavaScript. These royalty free standards are implemented by the major web browsers, 
and are what make web applications possible. By leveraging the technologies that encompass 
HTML5, millions of web developers are already able to code for Firefox OS. And apps built for 
Firefox OS are easy to port to another platform by using wrappers such as Phonegap 20 . 

The Platform That HTML5 Deserves 

The web is everywhere. Its on your computer, mobile phone, smart TV, and even in your video 
game consoles. The programming language of the web, JavaScript, is one of the most popular 
languages in the world. As already mentioned, when people talk about HTML5 they usually 
mean the collection of three technologies known as HTML, CSS and JavaScript. Recent advances 
in HTML have brought in a range of new features - advanced form controls, Web sockets, and 
more semantic markup - when compared to XHTML 1.0 and HTML 4.01. Advances in CSS have 
also introduced lots of new features, such as Flexbox and CSS Animations, that make it a lot 
easier to create beautiful responsive layouts. And recent advances in JavaScript have brought 
significant performance improvements and new capabilities, all while remaining easy to use for 
both beginners and seasoned developers alike. 

Firefox OS is in essence, an extension of the mobile web. By making HTML5 a first class citizen, 
Mozilla has opened its platform to millions of web developers. Even if some other browser 
vendors implement HTML5 in their mobile offerings, Firefox OS goes beyond that by offering a 
collection of APIs to access the underlying hardware and system using JavaScript. These APIs 
are collectively known as the WebAPIs. 



'http://phonegap.com 
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Accessing The Hardware Using The WebAPI 

Some earlier platforms also tried to create operating systems that used web technologies for app 
creation. For example, when the iPhone was introduced to the world, the only way to create 
apps was using web technologies. However, those web apps were limited in that they had no 
hardware or device access - meaning that only a limited range of applications could be built. 
When Apple then allowed developers to code apps in Objective-C, and also access the device's 
capabilities, it spurred a huge amount of innovation. Sadly, web apps did not gain access to the 
device's capabilities, and were thus left as "second-class citizens" - this made them unattractive 
to both users and developers alike, and unable to compete with native apps in that system. 

When we say device capabilities we actually mean accessing hardware and OS level features 
and services: We're talking about things such as updating the address book, sending SMS, and 
accessing the camera and media gallery. On Firefox OS, the WebAPI 2 x s are the means by which 
you will access many of those capabilities. 

Another earlier platform, WebOS, also offered hardware access via JavaScript but never tried 
to standardize its APIs. Mozilla is working with the W3C and other stakeholders to make sure 
that the WebAPIs are an open standard and that other browsers adopt them too. As these APIs 
are implemented by other browsers, your apps will require less and less changes to work across 
different platforms. 

It's important to emphasize that the WebAPIs are not exclusive to Firefox OS devices. Mozilla 
is implementing it for the other platforms on which Firefox runs, such as desktop and android. 
This way, you can use your open web app in Firefox OS, Firefox on the desktop and Firefox for 
Android. 

Freedom to Develop and Distribute 

Like everything that Mozilla does, Firefox OS is developed in the open and is free. All 
development can be followed on the Mozilla B2G repository 22 on GitHub. With Firefox OS 
you have the freedom to follow and contribute with the development of the system and you 
also have the freedom to distribute your applications on your own channels or on The Firefox 
Marketplace 23 . What's really awesome is that all the system applications are written in HTML5, 
so you can check them out and see how the are put together. 

The main idea is that you're not locked to Mozilla for anything. If you want to pick the source 
code for the system and change it for your own needs, so be it. If you need to build apps for 
internal use on your company, or if you want to distribute your creations only on your own web 
site, you're free to do it. Usually, in other platforms you're locked into the official app store as 
the only channel to distribute your apps. Firefox OS also has an official market called Firefox 
Marketplace which has an approval process but you're free to distribute your app outside this 
store if you want. Like in the web where you can host your web site anywhere you want, on 
Firefox OS you can do the same with your applications. 



21 https://developer. mozilla.org/en-US/docs/WebAPI 
22 https://github.com/mozilla-b2g/B2G 
23 https://marketplace. firefox. com/ 
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This comes with a small caveat, sadly: some of the WebAPIs are too security sensitive to just 
allow anyone to use them. To distribute apps that use some of the more "privileged" APIs, you 
will need to get your applications signed and reviewed by Mozilla's staff. 

Summary 

HTML5 is here to stay and will only get better. Firefox OS is the new open mobile operating 
system by Mozilla completely based on web technologies. This system is built on the open and 
offers a robust HTML5 implementation that goes beyond the other platforms by offering the 
WebAPI which is a collection of APIs to access hardware and operating system services using 
JavaScript. These new APIs are being standardized through the World Wide Web Consortium 
(W3C) and will hopefully be adopted by other browsers in the future. 

In the next chapter we'll quickly get you set up with everything you need to develop for Firefox 
OS. 



Setup For Firefox OS App 
Development 

The Gecko Engine 

Browsers use different engines for rendering web pages: Google Chrome and Opera use Blink (a 
fork of WebKit), Internet Explorer uses Trident, while Safari uses WebKit. Mozilla has its own 
engine, called Gecko which is used in Firefox desktop, Firefox for Android, and Firefox OS. As 
these products use the same engine, it is possible to develop for Firefox OS using the Firefox 
desktop browser (but with some caveats 24 ). 

What applications do you need? 

To develop and test apps made for Firefox OS you will need: 

• A recent version of the Firefox Browser 25 . 

• The Firefox OS Simulator 26 if you're running a device with Firefox OS 1.1. 

• A text editor for programming 27 . 

Be aware that the Firefox OS Simulator is made to work with devices running Firefox OS 
1.0 up to 1.1, devices running Firefox OS 1.2+ will be tested using the App Manager which 
we will talk more later. 

When this book was first written Firefox OS 1.1 was current and the official way of testing 
things was with the Firefox OS 1.1 Simulator. Mozilla is now transitioning to the new App 
Manager which is much better than the old simulator but unfortunately not able to connect to 
Firefox OS 1.1 devices. 

Since there are a lot of people running Firefox OS 1.1 and most of the devices sold in the 
retails market are still 1.1 devices we'll keep the Firefox OS 1.1 Simulator instructions but we'll 
duplicate any section related to that simulator and also present how to do the same tasks in the 
App Manager. I will present the App Manager content first because thats the current stuff and 
then present the content for the old simulator. 

The App Manager is bundled with Firefox 29 or newer. We'll describe it in detail on the chapter 
about App Manager. 

"Although the same engine is used for all Mozilla products, the version of the engine in Firefox OS is generally behind that of the desktop 
browser. This is because the release cycle of Firefox OS is currently slower than that of the Desktop browser. In practice, this will mean that 
some features may not be available (or work as expected) when you try them out in Firefox OS - so always make sure you test your applications 
on a device that runs Firefox OS. Also, be mindful that users might also be on different versions of Firefox OS, so they might not have all the 
bleeding edge features. Be sure to always provide a fallback in case where some feature is unavailable. 

25 http://getfirefox.com 

26 https://addons. mozilla.org/en-US/firefox/addon/firefox-os- simulator/ 

27 There are many good editors out there with different levels of complexity and features. A very popular one that I recommend for those 
that don't have a favorite one is SublimeText. Personally, I use WebStorm which is a complete IDE for web app creation. 
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App Manager Setup 

If you're running the current version of Firefox (a.k.a. 29 or newer) then you have the App 
Manager available to you. Having the App Manager is not enough though. You still need to 
install the simulators on the App Manager itself to be able to test things without hooking a 
device to your machine. Mozilla has extensive documentation about the App Manager 28 so if 
you want to dive a bit deeper check it out. 

The App Manager is able to manage multiple Firefox OS versions so you can install simulators 
for version 1.3, 1.4 and 2.0, remember that the higher the version number the earlier it is. And by 
earlier I mean buggy but since we can have multiple versions then we should just install them 
all so that we're able to test our apps with different Firefox OS versions. 

Lets take the new App Manager for a spin and install the stuff we'll need for later. To launch the 
App Manager go to the menu Tools -> Web Developer -> App Manager. 
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Where you can find the App Manager 



After you launch the App Manager you will see a screen like this 



28 https://developer. mozilla.org/en-US/Firefox_OS/Using_the_App_Manager 
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App Manager 



This tool will help you build and install web apps on compatible devices (i.e. 
Firefox OS). The Apps tab will assist you in the validation and installation 
process of your app. The Device tab will give you information about the 
connected device. Use the bottom toolbar to connect to a device or start the 
simulator. 

Useful links: 

• Documentation: Using the App Manager 

• How to setup your Firefox OS device 

• Troubleshooting 

• Install Simulator Add-on 

• Install Adb Helper Add-on 
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Not Connected. 











The App Manager Help 



You need to click the Install Simulator button and select the versions you want to install. 

The App Manager uses ADB to communicate with connected devices. It is able to handle all the 
ADB stuff for you if you install the ADB Helper Add-on available at Install the ADB Helper 
add-on 29 . 

My recommendation is to install all available versions of the simulator and the ADB Helper. 

29 https://ftp. mozilla.org/pub/mozilla.org/labs/fxos-simulator/ 
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The page to download Simulators and the ADB Helper 



Installing the Firefox OS Simulator 

If you have a device running Firefox OS 1.1 then you need to install the Firefox OS 1.1 Simulator 
because your device can't communicate with the new App Manager. 

After installing Firefox, the next step is the installation of the Firefox OS Simulator that will be 
used to test our applications. With Firefox installed and running, go to the Tools menu and select 
Add-ons. 
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Tools menu with *Add-ons** menu selected 



Using the search box on the top right corner, search for Firefox OS Simulator and install the 
add-on by clicking the install button. 
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Attention: If you're running Firefox 29 or newer and you have a device running 
Firefox OS 1.1 or earlier then you will need another version of the Firefox OS 1.1 
Simulator that is not currently listed on the add-ons marketplace. This version is 
BETA but its the best we've got right now. You can fetch it for Mac OS X 30 , Linux 31 or 
Windows 32 . Just drop the xpi file on Firefox and follow the installation instructions. If 
you want to follow up on the quest of making the Firefox OS 1.1 simulator work on 
Firefox 29 then check out bug request #1001590 it 33 . 



http://ftp.mozilla.org/pub/mozilla.org/labs/r2d2b2g/r2d2b2g-5.0pre7-mac.xpi 
'http^/ftp. mozilla.org/pub/mozilla.org/labs/r2d2b2g/r2d2b2g-5.0pre7-linux.xpi 
2 http://ftp. mozilla.org/pub/mozilla.org/labs/r2d2b2g/r2d2b2g-5.0pre7-windows. xpi 
3 https://bugzilla.mozilla.org/show_bug.cgi?id=1001590 
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After the installation of the add-on, you will be able to access the simulator by going to the menu 
Tools -> Web Developer -> Firefox OS Simulator. 
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Where you can find the simulator after is installed 

Alternatively, you can navigate to the Firefox OS Simulator 34 addon page, and download the 
simulator from there. 

Summary 

In this chapter we learned that all we need to develop Firefox OS apps is the Firefox browser, the 
App Manager and Firefox OS Simulators (and a good text editor). 

Now that we have setup all the tools we need, lets learn some basic concepts before we build our 
first app. 

34 https://addons. mozilla.org/en-US/firefox/addon/firefox-os- simulator/ 
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Before we get our hands dirty and build our first app, let's learn some basic concepts about 
developing for Firefox OS. We learned in the introduction that, just like web pages, apps in 
Firefox OS are based on HTML5. However, we haven't explained what makes Firefox OS apps 
different from regular web pages. 

If we use our collective knowledge about other mobile platforms we can see that native 
application generally will have: 

• A name and an icon that the user can press to launch the app. 

• Access to system services and hardware capabilities. 

Looking at the big picture, a Firefox OS app is just a web page that has an icon, a name and is 
usually able to work offline (depending on how the app is implemented). All the data about an 
application such as name, icon and more is defined in a application manifest file that is the focus 
of our next section. 

The Application Manifest 

The manifest 35 is a JSON 36 file that describes aspects of an hosted web app. Usually this file is 
called manifest.webapp and lives next to your main HTML file that is usually called index.html. 

Sample Manifest 

r 

"name": "Memos", 
"version" : "1.1", 

"description": "A simple memo taking app", 
" launch_path" : "/index . html " , 
"permissions": { 
"storage" : { 

"description": "Required for storing and retrieving notes." 

} 

}, 

"developer" : { 

"name": "Andre Garzia", 

"ur 1 " : "http : //andregarzia . com" 

}, 

" icons" : { 



'https://developer.mozilla.org/docs/Apps/Manifest 
'http://json.org 
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"60" : "/style/icons/icon_60 . png" , 
"128" : "/style/icons/icon_128. png" 



} 

} 



Above we can see the manifest for an application called memos 37 . Among other things it describes 
who created the application, which icons are used, what is the name of the app, what file is used 
to launch the app (in this case it is index.html), what hardware access permissions your app 
requires, etc. This file is used by Firefox OS to add the application to the device's home screen 
and by the Firefox Marketplace to display the application on the catalog as we can see in the 
image below. 



Memos I Firefox Marketplace 




fB- Google Q-'lDdlJ-JL*] 



Firefox Marketplace sign m 



o 



Memos 

Andre Garzia 



***** 2 Reviews 

This app is unavailable for your platform. 



A simple memo taking app 

A simple note taking application with 

Version 

Latest version: i.i 



Memos app shown at the Firefox Marketplace 

Note how the information from the manifest is used by the system to add the app to the 
homescreen, as we can see on the following screenshot. 



This is a sample app for Firefox OS as seen on the Firefox Marketplace for which the source code is on GitHub. 
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0 O O Firefox OS Simulator 



Camera Galeria 



Marketplace HERE Maps ToDos Memos 



Imgur Imac 



Memos on the simulator 

By gathering your HTML, CSS, JavaScript, and a manifest file you already have an application 
ready to run on Firefox OS. Moving on our topic about basic concepts let's learn more about 
what application types there are. 

Types of Application 

Firefox OS currently has two types of applications: hosted apps and packaged apps - though more 
types may become available in the future (e.g. custom keyboards and the ability to create other 
system services). 

• Hosted Apps: Are hosted on a web server just like normal websites. This means that when 
the user launches a hosted app, its content is loaded from the remote server (or from the 
cache, if available). 

• Packaged Apps: Are distributed as a zip file and copied to the device when installed. 
When the user launches a packaged app, its contents are loaded from the zip file instead 
of a remote server. 

There are pros and cons to both types. On the one hand, hosted apps are easier to maintain, as 
all you need to do is maintain files on your web server. However, it's harder to make them work 
offline because it requires the use of the much despised appcache 38 . Hosted apps are also limited 

38 https://developer. mozilla.org/pt-BR/docs/HTML/Using_the_application_cache 
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in which WebAPIs they can use, which means they can't do all the things a packaged app can 
do. 

On the other hand, packaged apps have all their content stored on the device - which means they 
are always available when the user is offline (and so avoid needing appcache). They also have the 
ability to access security-sensitive WebAPIs that are not available to hosted apps. Updating them 
can be a bit painful, because you need to upload any new version to the Firefox Marketplace - 
which means going through a review process, which can take some time. 

When trying to choose which type of application to build, consider: if you require advanced 
WebAPIs, then you should use a packaged app. However, if your application works fine without 
needing to access any advanced system services or device capabilities beyond those already 
available in a web browser, then always choose a hosted app. It is ok to use packaged apps if you 
don't have a place to host it. 

Above I mentioned that appcache can be problematic (which is sometimes required for hosted 
apps). Don't worry too much as there are tools available to make appcache generation and 
deployment easier 39 . 

In this book we're going to build packaged apps, as it will allow us to explore what is possible 
with the WebAPIs. However, most of what we will learn about manifests applies to hosted apps. 
If you want to know more about distributing hosted apps, check the hosted applications link at 
the developer hub 40 . 

Now that we've covered the two types of applications that Firefox OS supports, let's look at the 
different levels of system access they can have. 

Security Access Levels 

There are three security levels on Firefox OS - with each level having more access to APIs than 
the previous level. 

• Plain (a.k.a. web): This is the default level for all applications. This level applies to hosted 
apps and packaged apps that do not declare a type property in their manifest file. These 
apps have access to the common set of APIs found in browsers - but don't have access to 
any of Mozilla's WebAPIs. 

• Privileged: This type of app has access to all common APIs found in the Firefox browser, 
plus some additional ones, such as contacts, and system alarms. Only packaged apps 
can be privileged apps and the package must be digitally signed by the Firefox OS 
Marketplace. 

• Certified: For security reasons, this level is only available to Mozilla and its partners (e.g. 
phone manufacturers, telecoms, etc.). Certified apps are able to access all the APIs, such 
as telephony and more. An example of certified app is the Firefox OS dialer application. 



There are many useful tools out there, check out Gulp, Grunt, Volo, Yeoman, Bower. There is a lot of overlap among these tools, its a matter 
of preference which one you use. (I like Volo more than Grunt mostly because Volofiles are easier for me to read). 
40 https://marketplace. firefox. com/ developers/docs/hosted 
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During development, it is possible for us to access privileged APIs without needing any special 
permission from Mozilla. But when we want to distribute a privileged app, it first needs to go 
to the Firefox Marketplace. There, the code is checked as part of a rigorous approval process, 
and if it's found to be OK, it will be digitally signed - which tells users of Firefox OS that this 
application is allowed to access sensitive APIs. 

On the page about the WebAPIs on the Mozilla Developer Network 41 we can see what APIs are 
implemented on what platforms and what access level is needed to use each API. 

FileHandle API 

Provides support for writable files with locking support. 
Indexed DB 

Client-side storage of structured data with support for high-performance 
searches. 

Contacts API 6h Privileged 

Provides access to the user's contacts database, with support for adding, 
reading, and modifying contact information. 

Device Storage API Privileged Non-standard 

Allows apps to create, read, and change files stored in a central location 
on the device, such as the "pictures" folder on modern desktop platforms 
or the photo storage on mobile devices. 

Access levels for the APIs 

As we can see on the image above, any application can access the IndexedDB API and FileHandle 
API but only privileged apps can access the Contacts API and Device Storage API. 

Mozilla's WebAPIs 

Firefox OS provides us with the APIs that enable us to build applications that are just as capable 
as native apps on other platforms. Access to hardware and services is done through the WebAPIs. 
To learn more about the list of available APIs for the current Firefox OS version check out the 
WebAPI page on the Mozilla Wiki 42 . 

Lets review some code examples to see how easy those APIs are to use. Don't take this example 
as a full documentation of the WebAPIs, they are just a small sample to make you understand 
how we can access device features using JavaScript. 

Example #1: Making calls 

Imagine that you have an application that needs to open the dialer with a phone number already 
filled in. You can just use the following code: 



41 https://developer. mozilla.org/en-US/docs/WebAPI 
42 https://wiki.mozilla.org/WebAPI 
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Sending a phone number to the dialer 

var call = new MozActivity( { 
name: "dial", 
data : { 

number: "5555-9999" 

} 

}); 



This code makes a request to the dialer app to call a particular number. Note that this doesn't 
actually place a call - the user will still need to tap the dial button to place the call. Requiring 
explicit user action before executing some other action is pretty common: it's a good security 
pattern because it requires user interaction through consent before allowing something to 
happen. Other APIs that can place calls without user interaction are available for more elevated 
access levels. Certified apps can place calls without interaction for example. The API used in the 
code above, called "Web Activities", is available to all apps though. 

Check out the the Mozilla Blog for more information about Web Activites 43 . 

Example #2: Saving a contact 

Imagine that you have a company intranet and you want to provide a way to transfer a contact 
from the online intranet address book to the phone address book. You can do that with the 
Contacts API. 

Saving a contact 

var contact = new mozContact( ) ; 
contact . init( {name : "Odin"}); 

var request = navigator . mozContacts . save(contact) ; 
request . onsuccess = function() { 

// contact saved success ful ly 

}; 

request . onerror = function() { 

// there was an error while trying to save the contact 

}; 



This API creates an object with the contact data and saves it into the phone address book without 
requiring user interaction. Because access to contacts carries potential privacy implications, this 
API is only available for privileged apps. This pattern where you create an object with a success 
and an error callback is used in many of the WebAPIs. 

To learn more about this API, read the page about the Contacts API on the Mozilla Wiki 44 . 



'https://hacks.mozilla.org/2013/01/introducing-web-activities/ 
'https://wiki.mozilla.org/WebAPI/ContactsAPI 
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Example #3: Picking an image from the camera 

Imagine you are building an application that applies fancy filters to pictures. You want to place a 
button in your app that allows the user to pick a photo from a photo album or from the camera. 

Picking an image 

var getphoto = new MozActivity( { 
name: "pick", 
data : { 

type: [ " image/png" , " image/jpg" , " image/jpeg" ] 

} 

}); 

getphoto. onsuccess = function () { 

var img = document . createElement( " img" ) ; 

if (this . result . blob . type . indexOf( " image" ) != -1) { 

img.src = window . URL . createObjectURL(this . result . blob) ; 

} 

}; 

getphoto . onerror = function () { 

// error! 

}; 



Here we see another example of a Web Activity 45 . These activities are available to all applications. 
In this specific sample we're using the pick activity and passing in the MIME Types of the files 
that we wish to retrieve. When this code is executed, the system shows a screen to the user asking 
where he or she wants to retrieve the image from (camera, gallery, wallpapers). If the user selects 
an image, the success callback is triggered. If the user cancels the operation, the error callback 
is executed. On the image below, we can see the dialog that lets the user pick a photo from the 
device: 




Example of the pick activity 



'https://hacks.mozilla.org/2013/01/introducing-web-activities/ 
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Summary 

In this chapter we saw that, unlike regular web pages, both Firefox OS' hosted apps and packaged 
apps rely on a manifest file. We also saw that, from a security perspective, packaged apps can 
be "privileged" or "certified". Only privileged and certified apps can access Mozilla's powerful 
set of WebAPIs. The more sensitive WebAPIs are not available to hosted apps or to regular web 
pages. 

Now it's about time we get our hands dirty and create an app! 



Our First App 



e o o 


Firefox OS Simulator 








nos 


+ 



Welcome Memo 




Memos, a minimalist notepad app 



In this chapter we're going to build a simple Memos application, which is an application for 
taking notes. Before coding, let's review how this app works. 

The app has three screens. The first one is the main screen and has a list of your stored notes 
by title. When you click a note (or add a new one) you're moved to the detail screen that allows 
you to edit the content and title of the given note. This is shown in the figure below. 



Our First App 



© O O 



Firefox OS Simulator 



j!H3l2h43 




This is a note taking app. Use the plus sign 
in the topleft corner of the main screen to 
add a new memo. Click a memo to edit it. 
All your changes are automatically saved. 




Memos, editing screen 

On the screen shown above the user can choose to delete the selected note by clicking on 
trash icon. This will cause a confirmation dialog to be shown. 
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8 O O Firefox OS Simulator 



, 12h44 




Confirmation 

Are you sure you want to delete this 
memo? 



Delete 



* o I 9 



Memos, note removal confirmation screen 

The source code for Memos is available at the Memos Github Repo 46 (also available as a .zip 47 
file). I recommend you download the files, so it's easier to follow along. Another copy of the 
source code is available on the code folder inside the github repository for this book 48 . 

Memos uses IndexedDB 49 to store the notes and the Gaia Building Blocks 50 to build the interface. 
In a future update to this book I will talk more about the Gaia Building Blocks, but at the moment 
I am just going to use them. You can check the link above to learn more about them and what 
user interface tools they provide. 

The first step is to create a folder for the application, let's call this folder memos. 



Creating the app manifest 

Memos manifest is pretty straight forward. Create a file named manifest.webapp on the memos 
folder. Manifests are JSON 51 files that describes an application. In this file we place things such 
as the name of the app, who the developer is, what icons are used, what file is used to launch the 
app, what privileged APIs it would like to use, and more. 

46 https://github.com/soapdog/memos-for-firefoxos 

47 https://github.com/soapdog/memos-for-firefoxos/archive/master.zip 

48 https://github.com/soapdog/firefoxos-quick-guide 

49 https://developer. mozilla.org/en-US/docs/IndexedDB/Using_IndexedDB 

50 http://bmldingfirefoxos. com/building-blocks 

51 http://json.org 
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Below we can see the contents of the Memos app manifest. Attention when copying this data 
because it's very easy to place a comma on the wrong place and create an invalid JSON. 
There are many tools that you can use to validate JSON files but there is a special one 
that is built specifically for validating app manifests. You can check out this online tool at 
http://appmanifest.org/ 52 . To learn more about app manifests read this page on MDN about 
them 53 . 



Memos manifest file (manifest. webapp) 



1 


{ 




2 




"name": "Memos", 


3 




"version" : "1.1", 


4 




"description": "A simple memo taking app", 


5 




" launch_path" : "/index . html " , 


6 




"permissions": { 


7 




"storage" : { 


8 




"description" : "Required for storing and 


9 




} 


10 




}, 


11 




"developer": { 


12 




"name": "Andre Garzia", 


13 




"ur 1 " : "http : //andregarzia . com" 


14 




}, 


15 




" icons" : { 


16 




"60" : "/style/icons/icon_60.png", 


17 




"128" : "/style/icons/icon_128. png" 


18 




} 


19 


} 





Let's review the fields from the manifest above. 



Field 



Description 



This is the name of the application. 

This is the current version of the app. 

What file is used to launch your application. 

What API permissions your app requests. More information 

about this below. 

Who developed this application 

The icons used by the app in many different sizes. 



name 
version 
launch_path 
permissions 

developer 
icons 



The most interesting part of this manifest is the permissions field where we ask for the storage 
permission that allows us to use IndexedDB without size restrictions 54 (thanks to that permission 
we can store as many notes as we want - though we should be mindful not to use too much of 

52 http://appmanifest.org/ 

53 https://developer. mozilla.org/docs/Apps/Manifest 

54 To learn more about permissions read the page on MDN about app permissions. 
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the user's disk space!). 

Now that the manifest is ready let's move on to the HTML. 



Building the HTML 



Before we start working on the HTML, let's take a brief detour to talk quickly about the Gaia 
Building Blocks 55 , which are a collection of reusable CSS and JS with the look and feel of Firefox 
OS that we can use on our own apps. 

Just like on the Web, you're not required to use the look and feel of Firefox OS in your own 
app. Using or not using the Gaia Building Blocks is a personal decision - and a good applications 
should have its own distinctive style and user experience. The important thing to understand is 
that your app will not suffer any type of prejudice or penalty on the Firefox Marketplace by not 
using the Gaia look and feel. I am using it here because I am not a good designer so ready made 
UI toolkits appeal to me (it's either that or hiring a designer). 

The HTML structure that we use in this application was built following the patterns adopted by 
the Gaia Building Blocks where each screen is a <section> and the elements follow a predefined 
format. If you haven't already, download the source code from the memos repository 56 so that 
you have the files (including the Building Blocks) to use. For those not confident with git and 
GitHub, the files are also available as a .zip file 57 . 



Before doing anything else copy the shared and the styles folders that you obtained by 
downloading the Memos repository to the memos folder you created. This will allow use to 
use the Gaia Building Blocks in our app. 

Let's begin our index.html files by including the needed bits. 




Warning: The version of the Gaia Building Blocks I used for this app is not the 
most up-to-date available from Mozilla. Trying to update to the current version will, 
unfortunately, break the Memos app. In your own projects, however, always use the 
latest version of the Gaia Building Blocks. 



Including the Building Blocks 



55 http://buildingfirefoxos. com/building- blocks 

56 https://github.com/soapdog/memos-for-firefoxos 

57 https://github.com/soapdog/memos-for-firefoxos/archive/master.zip 
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1 <!DOCTYPE html> 

2 <html> 

3 <head> 



4 <meta charset="utf-8"> 

5 <link rel="stylesheet" type="text/css" href="style/base . ess" /> 

6 <link rel="stylesheet" type="text/css" href="style/ui . ess" /> 

7 <link rel="stylesheet" type="text/css" href="style/bui lding_blocks . ess" /> 

8 <link rel="stylesheet" type="text/css" 

9 href="shared/style/headers . ess" /> 

10 <link rel="stylesheet" type="text/css" 

11 href="shared/style_unstable/l ists . ess" /> 

12 <link rel="stylesheet" type="text/css" 

13 href="shared/style_unstable/toolbars . ess" /> 

14 <link rel="stylesheet" type="text/css" 

15 href="shared/style/input_areas . ess" /> 

16 <link rel="stylesheet" type="text/css" 

17 href="shared/style/conf irm . ess" /> 

18 <title> Memos </title> 



19 </head> 

On line 01 we declare the DOCTYPE as HTML5. From line 05 up to 15 we include the CSS from 
the various components that we're going to use in our app such as headers, lists, text entry fields 
and more. 

Building the main screen 

Now we can start building the various screens. As mentioned earlier, each screen used by our 
app is a <section> inside the HTML <body>. The body tag must have an attribute role with its 
value equal to application because that is used by the CSS selectors to build the interface, so our 
body tag will be <body role="application" >. Let's build the first screen and declare our body 
tag as well. 

1 <body role="application"> 

2 

3 <section role="region" id="memo- 1 ist"> 



4 <header> 

5 <menu type= "tool bar "> 

<a id=" new -memo" href="#"><span class="icon icon-add">add</span></\ 

7 a> 

8 </menu> 

9 <hl>Memos</hl> 

10 </header> 

11 Orticle id="memol_ist" data-type="list"></article> 



12 </section> 
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Our screen has a < header > containing a button to add new notes and the application name. The 
screen also has an <article> which will be used to hold the list of stored notes. We're going to 
use the button and the article IDs to capture events when we reach the JavaScript implementation 
part. 

Be aware that each screen is a fairly straight forward HTML chunk. Building these same screens 
in many languages usually requires a lot more work. All we're doing is declaring our containers 
and giving them IDs when we need to reference them later. 

Now that the main screen is done, let's build the editing screen. 

Building the editing screen 

The editing screen is a bit more complex because it also holds the dialog box used when the user 
tries to delete a note. 



1 <section role="region" id="memo-detai 1 " class="skin-dark hidden"> 

2 <header> 

<button id="back-to-list"><span class="icon icon-back" >back</span> 

4 </button> 

5 <menu type= "tool bar "> 

<a id="share-memo" href="#"><span class="icon icon-share">share</s\ 

7 pan> 

8 </a> 

9 </menu> 

10 <form action="#"> 

11 <input id="memo-title" placeholder "Memo Title" required="required" 

12 type="text"> 

13 <button type="reset"> Remove text</button> 

14 </form> 

15 </header> 

16 <p i d= "memo- area "> 

17 <textarea placeholder="Memo content" id="memo-content" ></textarea> 

18 </p> 

19 <div role="toolbar"> 

20 <ul> 

21 <li> 

22 <button id=" delete -memo" class="icon-delete">Delete</button> 

23 </li> 

24 </ul> 

25 </div> 

26 <form id="delete-memo-dialog" role="dialog" data-type="conf irm" 

27 class="hidden"> 

28 <section> 

29 <hl>Conf irmation</hl> 

30 <p>Are you sure you want to delete this memo?</p> 

31 </section> 



Our First App 



26 



<menu> 

< button id=" cancel -delete -act ion" > Cancel < /button > 
< button id=" con firm- delete -act ion" c 1 ass=" danger ">Delete< /button > 
</menu> 
</form> 
</section> 

At the top of the screen, represented by the < header > element, we have: 

• a back button to return to the main screen, 

• a text entry field that is used to hold the title of the given note, 

• and a button that is used to share the note over email. 

Below the top toolbar, we have a paragraph holding a <textarea> that holds the content of the 
note and then another toolbar with a trashcan button used to delete the current viewed note. 

These three elements and their child nodes are the editing screen. After them we have a < form> 
that is used as a dialog box containing the confirmation screen that is presented to the user when 
he or she tries to delete a note. This dialog box is pretty simple, it only contains the text of the 
confirmation prompt and two buttons; one for deleting the note and another for canceling the 
action. 

Now that we're closing this <section> we have all our screens implemented and the remaining 
HTML code is only there to include the JavaScript files and close the html file. 

<script src="/js/model . js"> </script> 
<script src="/js/app . js"> </script> 
</body> 
</html> 

Crafting the JavaScript code 

Now we're going to breathe life into our app by adding JavaScript. To better organize this code, 
I've divided the JavaScript code into two files: 

• model.js: contains the routines to deal with storage and retrieval of notes but does not 
contain any app logic or anything related to the interface or data entry. In theory, we 
could reuse this same file in other apps that required text notes. 

• app.js: attaches the HTML elements with their event handlers and contains the app logic. 

Both files should be placed inside a js folder next to the style and shared folders. 
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model.js 



We're going to use IndexedDB 58 to store our notes. Since we asked the storage permission on the 
app manifest we can store as many notes as we want - however, we should not abuse this! Firefox 
OS devices generally have very limited storage space, so you always need to be mindful of what 
data you store (users will delete and down-rate your app if it uses too much storage space!). And 
storing excessive amounts of data will have a performance penalty, which will make your app 
feel sluggish. Please also note that when you submit an application to the Firefox OS Marketplace, 
reviewers will ask you why you need unlimited storage space - if you can't justify why, your 
application will be rejected. 

The part of the code from model.js that is shown below is responsible for opening the connection 
and creating the storage. 



Important: This code was written to be understood easily and does not represent the best 
practices for JS programming. Some global variables are used (I'm so going to hell for this) 
among other tidbits. The error handling code is basically non-existant. The main objective of 
this book is to teach the workflow of developing apps for Firefox OS and not teaching best JS 
patterns. That being said, depending on feedback, I will update the code in this book to better 
reflect best practices if enough people think it will not impact the beginners. 



1 var dbName = "memos"; 

2 var dbVersion = 1; 



3 



4 var db; 

5 var request = indexedDB . open(dbName, dbVersion); 



6 




14 



15 request . onupgradeneeded = function (event) { 



16 



17 



console . log( "Running onUpgradeNeeded" ) ; 



18 



19 



db = event . target . result; 



20 



21 



if (! db . objectStoreNames . contains( "memos" ) ) { 



22 



58 https://developer. mozilla.org/en-US/docs/IndexedDB/Using_IndexedDB 
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23 console . log( "Creating objectStore for memos"); 

24 

25 var objectStore = db . createObjectStore( "memos" , { 

26 keyPath: "id", 

27 autolncrement : true 

28 }); 

29 objectStore. createlndex( "title", "title", { 

30 unique: false 

si }); 

32 

33 console . log( "Adding sample memo"); 

34 var sampleMemol = new Memo( ) ; 

35 sampleMemol . title = "Welcome Memo"; 

36 sampleMemol . content = "This is a note taking app. Use the plus sign " + 

37 "in the topleft corner of the main screen to " + 

38 "add a new memo. Click a memo to edit it. All " + 

39 "your changes are automatically saved."; 

40 

41 objectStore . add(sampleMemol ) ; 

42 } 



43 } 



Important: Forgive me again for the globals, this is an educational resource only. Another detail 
is that I removed the comments from the source code to save space in the book. If you pick the 
source from GitHub you will get all the comments. 



The code above creates a db object and a request object. The db object is used by other functions 
in the source to manipulate the notes storage. 

On the implementation of the request. onupgradeneeded function we also create a welcome 
note. This function is executed when the application runs for the first time (or when the database 
version changes). This way once the application launches for the first time, the database is 
initialized with a single welcome note. 

With our connection open and the storage initialized its time to implement the basic functions 
for note manipulation. 
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1 function Memo( ) { 

2 this. title = "Untitled Memo"; 

3 this. content = ""; 

4 this. created = Date.now(); 

5 this . modi fied = Date.now(); 

6 } 

7 

8 function 1 istAl lMemoTitles( inCal lback) { 

var objectStore = db . transaction( "memos" ). objectStore( "memos" ) ; 
10 console . log( "Listing memos..."); 

11 

objectStore . openCursor( ). onsuccess = function (event) { 

13 var cursor = event . target . result; 

14 if (cursor) { 

15 console . log( "Found memo #" + cursor . value . id + 

16 " - " + cursor . value . title) ; 

17 inCal lback(null , cursor .value) ; 

18 cursor . continue( ) ; 

19 } 

20 }; 

21 } 

22 

23 function saveMemo( inMemo, inCal lback) { 

var transaction = db . transaction( /""memos") , "readwrite" ) ; 
25 console . log( "Saving memo"); 

26 

transaction . oncomplete = function (event) { 

28 console. log( "All done"); 

29 }; 

30 

31 transaction . onerror = function (event) { 

console . error( "Error saving memo:", event); 

33 inCallback({ 

34 error : event 

35 }, null); 
36 

37 }; 

38 

var objectStore = transaction . objectStore( "memos" ) ; 

40 

41 inMemo . modi fied = Date.now(); 

42 

43 var request = objectStore . put( inMemo) ; 

44 request . onsuccess = function (event) { 

45 console . log( "Memo saved with id: " + request . result) ; 

46 inCallback(null, request . result) ; 



Our First App 



30 



47 

48 }; 

49 } 
50 

51 function deleteMemo( inld, inCallback) { 

52 console . log( "Deleting memo..."); 

53 var request = db . transaction( /""memos"7 , 

54 "readwrite" ) . objectStore( "memos" ) . delete( inld) ; 

55 

56 request . onsuccess = function (event) { 

57 console . log( "Memo deleted!"); 

58 inCallback( ) ; 

59 }; 

60 } 



On the piece of code above we create a constructor function that creates new Memos with some 
fields already initialized. After that we implement functions for listing, saving and removing 
notes. Many of these functions receive a callback parameter called inCallback which is a 
function to be called after the function does its thing. This is needed due to the asynchronous 
nature of IndexedDB. All callbacks have the same signature which is ca 1 1 back ( error , va 1 ue ) 
where one of the values is null depending on the outcome of the previous function. 



Since this is a beginner book I've opted not to use Promises 3 since many beginners are not 
familiar with the concept. I recommend using such concepts to create easier to maintain code 
that is more pleasant to read. 

'littps^/developer.mozilla.org/en-US/docs/Mozilla/JavaScriptcodemodules/Promise.jsm/Promise 



Now that our note storage and manipulation functions are ready, let's implement our app logic 
in a file called app.js. 

app.js 

This file will contain our app logic. Since the source code is too large for me to place it all at once 
on the book, I will break it in parts and explain each part piece by piece. 
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1 var listView, detailView, currentMemo, deleteMemoDialog; 

2 

3 function showMemoDetai 1 ( inMemo) { 

4 currentMemo = inMemo; 

5 displayMemo( ) ; 

6 1 istView . classList . add( "hidden" ) ; 
detai IView .classList . remove ( "hidden" ) ; 

8 } 

9 
10 

11 function displayMemo( ) { 

document . getElementById( "memo-title" ) .value = currentMemo. title; 
document . getElementById( "memo-content" ) . value = currentMemo . content ; 

14 } 
15 

16 function shareMemo() { 

17 var shareActivity = new MozActivity( { 

18 name: "new", 

19 data: { 

20 type: "mail", 

21 body: currentMemo . content , 

url : "mai lto : ?body=" + encodeURIComponent(currentMemo . content) + 
23 "&subject=" + encodeURIComponent(currentMemo . title) 

24 

25 } 

26 }); 

shareActivity . onerror = function (e) { 

28 console . log( "can ' t share memo", e); 

29 }; 

30 } 
31 

32 function textChanged(e) { 

currentMemo .title = document . getElementById( "memo-title" ) . value; 
currentMemo . content = document . getE lementBy Id ( "memo -content" ). value; 

35 saveMemo( currentMemo, function (err, succ) { 

36 console . log( "save memo callback ", err, succ); 

37 if ( !err) { 

38 currentMemo . id = succ; 

39 } 

40 }); 

41 } 
42 

43 function newMemo() { 

44 var theMemo = new Memo( ) ; 

45 showMemoDeta i 1 ( theMemo ) ; 

46 } 
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At the beginning we declare some global variables (yuck!!!) to hold references to some DOM 
elements that we want to use later inside some functions. The most interesting global is 
currentMemo which is an object that holds the current note that the user is reading. 

The showMemoDetai 1 ( ) and displayMemo( ) functions work together. The first one loads the 
selected note into the currentMemo and manipulates the CSS of the elements so that the editing 
screen is shown. The second one picks the content from the currentMemo variable and places it 
on the screen. We could do both things on the same function but having them separate makes it 
easier to experiment with new implementations. 

The shareMemo() function uses a WebActivity 59 to open the email application with a new 
message pre-filled with the selected notes content. 

The textChanged( ) function picks the data from the entry fields and place them into the 
currentMemo object and then saves the note. This is done because the application is an auto-save 
app where your content is always saved. All alterations on the content or title of the note will 
trigger this function and the note will always be saved on the IndexedDB storage. 

The newMemo( ) function creates a new note and opens the editing screen with it. 



1 function requestDeleteConf irmation( ) { 

deleteMemoDialog . classList . remove ( "hidden" ) ; 

3 } 
4 

5 function closeDeleteMemoDialog( ) { 

deleteMemoDialog .classList . add( "hidden" ) ; 

7 } 
8 

9 function deleteCurrentMemo( ) { 
10 closeDeleteMemoDialog( ) ; 

deleteMemo(currentMemo . id, function (err, succ) { 
console . log( "cal lback from delete", err, succ); 

13 if ( !err) { 

14 showMemoList( ) ; 

15 } 

16 }); 

17 } 
18 

19 function showMemoList( ) { 

20 currentMemo = null; 

21 refreshMemoList( ) ; 

1 istView .classList . remove ( "hidden" ) ; 
detai IView .classList . add ( "hidden" ) ; 

24 } 



The requestDeleteConf irmation( ) function is responsible for showing the note removal 
confirmation dialog. 



'https://hacks.mozilla.org/2013/01/introducing-web-activities/ 
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The closeDeleteMemoDialog( ) and deleteCurrentMemo( ) are triggered by the buttons on the 
removal confirmation dialog. 

The showMemol_ist( ) function does some clean up before showing the list of stored notes. For 
example, it cleans the content of currentMemo since we're not reading any memo yet. 

1 function refreshMemol_ist( ) { 



2 if ( !db) { 

3 // HACK: 

4 // this condition may happen upon first time use when the 

5 // indexDB storage is under creation and refreshMemoList( ) 

6 // is called. Simply waiting for a bit longer before trying again 

7 // will make it work. 

8 console . warn( "Database is not ready yet"); 

9 setTimeout(refreshMemoList, 1000); 

10 return; 

11 } 

12 console . log( "Refreshing memo list"); 

13 

var memoListContainer = document . getElementById( "memoList" ) ; 

15 
16 

17 while (memoListContainer . hasChi ldNodes( ) ) { 

18 memoListContainer . removeChi Id (memoListContainer . lastChi Id) ; 

19 } 

20 

21 var memoList = document . createElement( "ul ") ; 

22 memoListContainer . appendChi ld(memoList) ; 

23 

24 1 istAl lMemoTitles( function (err, value) { 

25 var memoltem = document . createElement( " 1 i ") ; 

26 var memoP = document . createElement( "p" ) ; 

var memoTitle = document . createTextNode( value . title) ; 

28 

memoltem . addEventListener( "cl ick" , function (e) { 

30 console . log( "cl icked memo *" + value. id); 

31 showMemoDetai 1 (value) ; 

32 

33 }); 
34 

35 memoP . appendChi ld(memoTitle) ; 

36 memoltem . appendChi ld(memoP) ; 

37 memoList . appendChi ld(memoltem) ; 

38 
39 

40 }); 



41 } 
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The refreshMemol_ist( ) function modifies the DOM by building element by element the list of 
notes that is displayed on the screen. It would be a lot easier to use some templating aid such as 
handlebars 60 or underscore 61 but since this app is built using nothing but vanilla javascript we're 
doing everything by hand. This function is called by showMemol_ist( ) that was shown above. 

These are all the functions used by our app. The only part of the code that is missing is the 
initialization of the event handlers and the initial call of refreshMemoList( ). 

1 window . onload = function () { 



2 // elements that we're going to reuse in the code 

listView = document . getElementById( "memo- 1 ist" ) ; 
4 detailView = document . getElementById( "memo-detai 1 ") ; 

deleteMemoDialog = document . getE lementBy Id ( "delete -memo- dialog" ) ; 

6 

7 //All the 1 isteners for the interface buttons and for the input changes 

8 document . getE lementBy Id ( " back -to- 1 ist" ) 

9 . addEventl_istener( "cl ick" , showMemoList) ; 

10 document . getE lementBy Id ( "new-memo" ) 

11 . addEventl_istener( "cl ick" , newMemo); 
document . getElementById( "share-memo" ) 

13 . addEventl_istener( "cl ick" , shareMemo); 

14 document . getElementById( "delete-memo" ) 

. addEventl_istener( "cl ick" , requestDeleteConf irmation) ; 

16 document . getE lementBy Id ( "confirm -delete -act ion" ) 

17 . addEventListener( "cl ick" , deleteCurrentMemo) ; 

18 document . getE lementBy Id ( "cancel -delete -act ion" ) 

. addEventl_istener( "cl ick" , closeDeleteMemoDialog) ; 

20 document . getElementById( "memo-content" ) 

21 . addEventl_istener( " input" , textChanged) ; 
document . getElementById( "memo-title" ) 

. addEventl_istener( " input" , textChanged) ; 

24 

25 // the entry point for the app is the following command 

26 refreshMemoList( ) ; 

27 



28 }; 

Now all files are ready and we can begin trying our application on the simulator. There are 
two ways of doing this depending if you're using the App Manager or the old Firefox OS 1.1 
simulator. In the following section we'll show both. There will be specific chapters on each 
technology later. 

If you're running Firefox 29 or newer then you have the App Manager, if you're running an 
older version then you can use the old simulator. Be aware that the App Manager is only able to 
connect to Firefox OS 1.2+ devices. 



6 http://handlebarsjs.com/ 
61 http://underscorejs.org/ 
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If you have a Firefox OS 1.1 device and you're running Firefox 29 then install the Firefox OS 
1.1 simulator version 5.0 available for Mac OS X 62 , Linux 63 or Windows 64 . If you install this 
simulator you will be able to follow the instructions for the old Firefox OS 1.1 simulator and be 
able to connect your device. 

If your device running Firefox OS 1.1 is unlocked and able to receive version 1.2 or later then you 

should upgrade because it will make your life a lot easier. The Geeksphone Keon, Geeksphone 

Peak and Geeksphone Revolution have daily Firefox OS builds available at http://downloads.geeksphone.com/ 65 . 

The ZTE Open can also be upgraded following the instructions at Upgrading your ZTE Open to 

Firefox 1.1 or 1.2 (fastboot enabled) 66 . The LG Fireweb can't be upgraded, if you are like me and 

don't like this then go bug LG to open/upgrade their device on Twitter. The Alcatel One Touch 

Fire can be unlocked but this type of instruction is beyond this book. 

A Notice: This bug request #100 1 59 0 67 on bugzilla will fix the current problem of not being 
able to run the Firefox OS 1.1 simulator on Firefox 29. 



Testing the app with the App Manager 

Before we try our application on the simulator we'd better check out if the files are in the correct 
place. Your memos folder should look like this one: 

3 index.html 

& app.js 
ji model.js 
9 manifest.webapp 
9 README 
L, shared 
► S style 

List of files used by Memos 

If you have a hunch that you wrote something wrong, just compare your version with the one 
on the memos github repository 68 (There is also a copy of the source code in a folder called code 
on the book repository 69 ). 

To open the Simulator Dashboard go to the menu for Tools -> Web Developer -> App Manager. 

62 http://ftp. mozilla.org/pub/mozilla.org/labs/r2d2b2g/r2d2b2g-5.0pre7-mac.xpi 
63 http://ftp.mozilla.org/pub/mozilla.org/labs/r2d2b2g/r2d2b2g-5.0pre7-linux.xpi 
64 http://ftp. mozilla.org/pub/mozilla.org/labs/r2d2b2g/r2d2b2g-5.0pre7-windows.xpi 
65 http://downloads. geeksphone. com/ 

66 https://hacks.mozilla.org/2014/01/upgrading-your-zte-open-to-firefox-l-l-or-l-2-fastboot-enabled/ 
67 https://bugzilla.mozilla.org/ show_bug.cgi?id= 1001590 
68 https://github.com/soapdog/memos-for-firefoxos 
65 https://github.com/soapdog/guia-rapido-firefox-os 
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Where you can find the App Manager 



With the App Manager open, click the Add Packaged App option on the Apps tab and browse 
to where you placed the memos files and select that folder. 



Our First App 



©OO fv| | n box (43... [jf] Preview £J atom edit... ^ atom/doc... <j§> Split sere... j App Mana... X 



(+j x4 about:app-manager C | 09 (H~ Google Q ; & ♦ # Q 

P_] My Server - Pi Prog - Q Art - P_] MozDev - P_] Tangis - Q WebAPI I MDN fon.nu (overlay) pinboard 





Make sure you're on 'Apps' 



No projects. Add a new 
packaged app below (local 
directory) or a hosted app 
(link to a manifest file). 



[Click the 'Add Packaged App 1 option 




Adding a new app 

If everything works as expected you will see the Memos app on the list of apps. 
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Andre Carzia 

/Users /soapdog/mozil la/me mos- for- firefoxos 

A simple memo taking app 



Memos packaged 
A simple memo taking app 



Manifest Editor save 



description: "A simple nemo taking app" 

> developer Object 
^ icons Object 

launch_path I " / index . html " 
name "Memos" 

► permissions Object 
version "1.1* 



Add Packaged App 
Add Hosted App 



Help 


http://example.com/app/manifest.webapp O 




Not Connected. No device found. Plug a device or Start Simulator 





Memos showing on the App Manager 



After adding your application, click the Start Simulator button and run one of your installed 
simulators. If you haven't installed any simulator yet, I suggest you follow the instructions on 
screen and install them all. 

With the Simulator running press the Update button on the memos listing on the App Manager 
to install memos on the running Simulator. After the installation the memos icon will appear at 
the Simulator home screen. You can just click it to run your app. 
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Memos installed on the Simulator 



Congratulations! You created and tested your first app. It's not a complex or revolutionary app 
- but I hope it helped you understand the development workflow of Firefox OS. As you can see, 
it's not very different from standard Web development. 

Remember that whenever you alter some of the source files you need to press the Update button 
to update the copy of the app that is stored on the running Simulator. 



Testing the app on the simulator 

Before we try our application on the simulator we'd better check out if the files are in the correct 
place. Your memos folder should look like this one: 



Our First App 



40 



J index.html 

«? app.js 
£[i model.js 

9 manifest.webapp 

■ README 
shared 

£j style 



List of files used by Memos 

If you have a hunch that you wrote something wrong, just compare your version with the one 
on the memos github repository 70 (There is also a copy of the source code in a folder called code 
on the book repository 71 ). 

To open the Simulator Dashboard go to the menu for Tools -> Web Developer -> Firefox OS 
Simulator. 
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How to open simulator dashboard 

With the dashboard open, click the Add Directory button and browse to where you placed the 
memos files and select the app manifest. 

70 https://github.com/soapdog/memos-for-firefoxos 
71 https://github.com/soapdog/guia-rapido-firefox-os 
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Adding a new app 

If everything works as expected you will see the Memos app on the list of apps. 

DaSh bOard Add Directory 



Q Memos Packaged App 
Last updated: just now 
Open Location /Users/soapdog/Dropbox/leanpub/firefoxosdesenvolvendo/rnanuscript/code/memos/manifest.webapp 
Validation Result: OK 

Memos showing on the dashboard 

When you add a new application, the simulator will launch with your new app running - 
allowing you to test it. Now you can test all the features for Memos. 

Congratulations! You created and tested your first app. It's not a complex or revolutionary app 
- but I hope it helped you understand the development workflow of Firefox OS. As you can see, 
it's not very different from standard Web development. 

Remember that whenever you alter some of the source files you need to press the Refresh button 
to update the copy of the app that is stored on the simulator. 



Summary 

In this chapter we built our first application for Firefox OS and saw it running on the simulator. 
In the next chapter we're going to check out the developer tools that comes bundled with Firefox, 
they will make your life a lot easier when developing applications. 



Developer Tools 



Firefox has many tools to help web developers do their job. Many people are still using FireBug 72 
and haven't realize that Firefox now has its own built-in tools. In this chapter we're going to 
review the tools that are most useful for developing apps for Firefox OS. 

If you're interested in learning more about these tools, and what other dev tools goodness is 
about to land in Firefox, check out the developer tools 73 page on Mozilla's Developer Network 
(really, go check that link! I will wait). 

Introducing the Responsive Design View 

A common workflow in Web development is changing a HTML file and then reloading the 
page in the browser to see what's changed. Unless you are using something like Grunt or Volo, 
generally there won't be the need for a compilation step or similar. Even though the Firefox OS 
Simulator permits you to use that same workflow, the emulator is currently restricted to one 
resolution (480x320). This is less than ideal if you are also designing your application to work on 
tablets, phablets, giant TVs, or anything in between. 

To check how your app will look on any screen resolution, you can use Firefox' s Responsive 
Design View tool to change the screen (and viewport). It can be enabled by going to the Tools 
menu -> Web Developer -> Responsive Design View as shown in the image below. When you 
activate this tool, the window will change so that you can alter the viewport size using the drag 
corners or the selection box. 



72 https://addons. mozilla.org/pt-BR/firefox/addon/firebug/ 
73 https://developer. mozilla.org/en-US/docs/Tools 
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Activating Responsive Design View 

Using the responsive design view is specially useful for testing out media queries 74 , as it allows 
you to resize the screen and see how your site responds to changes in layout in real time. Another 
great feature of the Responsive Design View is that you can save predefined sizes. If you know 
what viewport sizes you are targetting, then your can quickly check different viewport sizes 
without needing to resize the actual browser window. 

74 https://developer. mozilla.org/en-US/docs/Web/Guide/CSS/Media_queries 
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Responsive Design View Sample 

At the time of writing, most of the Firefox OS phones that are on the market are running on 
a 480x320 resolution - and at a pixel density of about 96 pixels-per-inch. However, you should 
expect this to change as new Firefox OS hardware becomes available as time goes on: screens 
will likely pack more pixels and have higher pixel densities (just like Apple's retina displays). 

To future proof your app, don't hard-code your CSS to any resolution or pixel density. Instead, 
you should use media queries and the responsive design methodology to create apps that adapt 
to any screen size. To learn more about responsive design, I recommend the following books 
Responsive Web Design 75 and Mobile First 76 . 

In summary, the responsive design view allows us to test our web applications using many 
different screen sizes without the need to resize the Firefox browser window itself. In my humble 
opinion this is one of the most useful web developer tools available - but it has one big limitation: 
it does not currently allow you to test different pixel densities (i.e. to see what your site would 
look like on a "retina" display or better). 



http://www.abookapart.com/products/responsive-web-design 
6 http://www.abookapart. com/products/mobile-first 
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Developer tools 

Firefox's developer tools are similar to FireBug and the tools available in other modern browsers. 
Using these tools you can execute and debug your JavaScript using the console 77 , and manipulate 
both the DOM and the CSS on the current page. 

To bring up the console, you can either: 

1 * Go to "Tools menu > Web Developer > Web Console" . 

• right-click on the page you want to debug, and select "Inspect Element", then click on 
"Console" tab. 
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JavaScript Console 

Besides the JavaScript Console there are many other tools available such as the style editor 78 , the 
network monitor 79 , the JavaScript profiler 80 , the JavaScript debugger 81 , the page inspector 82 and 
many others. 

77 https://developer. mozilla.org/en-US/docs/Web/API/console 
78 https://developer. mozilla.org/en-US/docs/Tools/Style_Editor 
79 https://developer. mozilla.org/en-US/docs/Tools/Network_Monitor 
80 https://developer. mozilla.org/en-US/docs/Tools/Profder 
81 https://developer. mozilla.org/en-US/docs/Tools/Debugger 
82 https://developer. mozilla.org/en-US/docs/Tools/Page_Inspector 
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In the application we've built in the previous chapter, we used the console to check the progress 
of our application. This is a pretty powerful way to debug our apps - but some developers are 
still using alert( ) all over their JavaScript code as their "debug tool". 

Usingalert( ) is really bad because if one forgets to remove any alert ( )s, it's the user's who will 
ultimately pay the price. Using the console avoids this problem as it harmlessly (and silently!) 
routes all messages to a place that user's don't normally access - so it doesn't disrupt the user 
experience. Using the console also means you don't need to remove your console messages from 
your code, unless you really want to. This can help with code maintenance and debugging if 
things do go wrong (as they generally do with any software!). 

Learning how to properly use the developer tools bundled with Firefox (or whatever browser 
you're using) is an important step in becoming a better developer. That's why I advise everyone 
to check the links above and get more familiar with the various tools available in Firefox. 

One special tool that was not mentioned above is the remote debugger 83 . That tool allows us to 
connect to a phone running Android or Firefox OS, and use the developer tools to debug the 
code that is running on the device in real time. 

Summary 

This chapter provided a brief tour of the developer tools that come bundled with Firefox. Using 
these tools will make your development process easier, specially when you use them together 
with the Firefox OS simulator. They are an indispensable combination for putting together an 
application. In the next chapter we're going to learn more about the simulator and how to make 
the best use of it. 



'https://developer.mozilla.org/en-US/docs/Tools/Remote_Debugging 
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► permissions Object 
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Not Connected. No device found. Plug a device or Start Simulator 





Firefox OS Simulator Dashboard 

We've setup the Simulator in the chapter about preparing the environment and we used it on 
the chapter about building our first app. Now we're going to take a deeper look into the App 
Manager features and learn how to do the most common tasks. 

To learn more about it, check out the Firefox OS: Using the App Manager page 84 on MDN. 



A Remember: that if you are using a device running Firefox OS 1.1 or older then you need 
to use the Firefox OS 1.1 Simulator extension with it and not the App Manager. This 
Simulator is explained in the next chapter. 



'https://developer.mozilla.org/docs/Mozilla/Firefox_OS/Using_the_App_Manager 
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Adding Apps 

You can add both hosted and packaged apps to the App Manager. Lets see how to add each type 
of app: 



Adding packaged apps 

You already saw how to add packaged apps to the App Manager during our first app creation, 
but we're going to do a recap so I can show you what else is possible. 

To add a new packaged application click the Add Packaged App button on the App Manager 
Dashboard as shown in the screenshot below. 
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Not Connected. No device found. Plug a device or 
Start Simulator 



Showing the Add Packaged App option that adds a packaged app to the App Manager 



When you click on the button highlighted on the image, Firefox opens a file selection dialog. 
You should browse your hard drive and select the folder that contains the manifest file for the 
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application that you want to add to the App Manager. If there are no issues with your manifest 
then your app will be addes to the list on screen. 

Adding hosted apps 

If you're building a hosted app then you should test it by using a web server. Do not try to use 
the method described above for hosted apps because you may miss some errors that will only 
happen on a hosted environment - such as serving the manifest with the wrong MIME type. Note 
that the simulator won't warn you about things like incorrect MIME types, but it's important to 
get such things right if you submit your app to the Mozilla Marketplace. 

Most of the hosted apps are not applications built exclusively for Firefox OS but responsive design 
based websites that are able to adapt themselves to different devices and resolutions. These web 
apps usually have a complex backend that needs to be in-place for the application to work and 
that's why you need to test the app using a real web server running your backend stuff. 

To run your app in the simulator, fill the URL of your application in the text entry box and click 
the Add Hosted App button. 





Fill your manifest URL and 
click the Add Hosted App 






Add Packaged App 






Add Hosted App J- 






http://example.com/app/mamfest.webapp 




Adding a hosted app to the App Manager 



After clicking the button, the manifest is verified and if it is correct the application will be added 
and the App Manager. 

Running your app 

To run your application click the Start Simulator button. After that you will be able to select 
which of the installed Simulator you want to run. 

Once you have a Simulator running you can click the Update button inside your application 
listing and it will install the app on the running Simulator. 

The application icon will appear at the home screen of the Simulator once the installation is 
complete. You can just click it to run. 
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Updating your app 

Every time you change some of your files and want to test again on the Simulator you need to 
press the Update button to update the installation of your app on the running Simulator. 



Debugging 

After the application is added to a running Simulator we're able to debug it by clicking the 
Debug button in the application listing. This will launch the your app on the running Simulator 
and open a JavaScript Console connected to your app. 
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Manifest Edftor save 



When the Simulator is runing you 
are able to use the 'debug' button 
toiopen the developer tools connected 



nam to your app. 

► permissions ' — — Object 



version 



"1.1" 



What button to press 
After pressing this button you will see a screen like this: 
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Developer Tools connected to the app running on the simulator 



With the tools connected to your app you can test your JavaScript, debug your DOM, edit styles, 
etc. Like those startup guys like to say: pivot until your app is good. 

Once your app is running well on the simulator it's time to test on a real device. 



Testing apps on a real device 

Nothing replaces testing on a real device. On the simulator, you test things by using a mouse and 
clicking on a computer screen; while on a real device you use your fingers on a touchscreen and 
by using physical buttons. Its a very different user and development experience. 

As an example why this type of testing matters, let me tell you a brief story: Some years ago, 
Raphael Eckhardt (the designer who created the cover of this book) and I were building a puzzle 
game not that disimilar to Bejeweled. Our game involved dragging and dropping some pieces on 
a board and was working pretty well on the simulator. 

When we then tested the game on an actual phone we realized our game components were not 
touch friendly at all. When placing a hand over the screen the board would vanish behind the 
hand. Even worst, the pieces the users were supposed to drag were smaller than the user's finger 
tip, so the user couldn't see what they were doing! In summary, our UX sucked very badly. That 
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happened because we kept trying things only on the simulator using a mouse that had a tiny 
cursor. When we decided to try with our fatter-than-a-cursor fingers we realized that we need 
to rework our UI. 

To avoid having a similarly frustrating experience, always test on a real device. . . or two, or more 
if you can get your hands on multiple devices. Test often with simple prototypes. Otherwise, you 
can waste valuable time and money having to recreate assets. 

Connecting with a Firefox OS device 

If you have a Firefox OS device (and have any needed drivers installed) then you can push apps 
directly from the App Manager to the device if the device is connected to your computer. When 
the App Manager detects that you plugged a Firefox OS phone, it will display the id of the phone 
on the bottom next to the Start Simulator button. 

oo 



This is my conn ected device. The 
name will vary. 

Add Packaged App 



Add Hosted App 

http://example.eom/a 



j/ manifest, webapp 



o 
o 



Not Connected. Connect to: 7134BFCC or Start Simulator 



Device Connected! 



If you press that button. The phone will ask for permission to establish a debugging connection 
with the App Manager, you need to grant that. Once that connection is made you will be able to 
use the Update and Debug buttons on your app listing to install and debug your application on 
the connected device just like you did with the running Simulator. 



Summary 

In summary, the App Manager is fantastic. Its much better than the old Firefox OS 1.1 Simulator 
Extension since it has better developer tools and can run multiple Firefox OS versions. We can 
envision the App Manager getting better and better with its built-in manifest editor and more. 

Besides feeling awesome and empowered, by this point in the book you hopefully have a good 
grasp of the workflow for building apps for Firefox OS. 
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In the next chapter we'll talk about the old Firefox OS 1.1 Simulator Extension. This is the only 
way to connect to devices running Firefox OS 1.1. The chapter is really similar to this one. 
Actually its the same content but adapted for the different UI. 

After the Simulator chapter, we'll talk about distributing your application. 
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MemOS Packaged App 
Last updated: 25 days ago 

Open Location AJsers/soapdog/memo/manifestwebapp 
Validation Result: OK 



□ Push C Refresh Connect 



n Imgur Image Uploader Packaged App 

_» Last updated: 23 days ago 



Open Location AJsers/soapdog/mozilla/firefoxos-sample-a. . 
Validation Result: OK 



Receipt: None 



Q Push C Refresh /■ Connect 



Receipt: None 



ToDoS Packaged App 
Last updated: 26 days ago 

Open Location /Users/soapdog/mozillarfirefoxos-sample-a 
Validation Result: OK 



□ Push C Refresh >• Connect 



Receipt: None 



Firefox OS Simulator Dashboard 



A Attention: This chapter is here for compatibility with devices running Firefox OS 1.1. 
The current method for testing and debugging apps is the App Manager which we 
talked about in the previous chapter. The content of this chapter is just for people testing 
stuff on Firefox OS version 1.1. 
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A Attention: If you're running Firefox 29 or newer and you have a device running 
Firefox OS 1.1 or earlier then you will need another version of the Firefox OS 1.1 
Simulator that is not currently listed on the add-ons marketplace. This version is 
BETA but its the best we've got right now. You can fetch it for Mac OS X 85 , Linux 86 or 
Windows 87 . Just drop the xpi file on Firefox and follow the installation instructions. If 
you want to follow up on the quest of making the Firefox OS 1.1 simulator work on 
Firefox 29 then check out bug request #1001590 it 88 . 

We've installed the Firefox OS Simulator in the chapter about preparing the environment and 
we used it on the chapter about building our first app. Now we're going to take a deeper look 
into the simulator features and learn how to do the most common tasks. 

To learn more about it, check out the Firefox OS Simulator documentation 89 on MDN. 

Remember that if you are using a device running Firefox OS 1.2+ then you need to use the 
App Manager with it and not the Firefox OS Simulator. The App Manager was described in the 
previous chapter. 

Adding Apps 

You can add both hosted and packaged apps to the simulator. Lets see how to add each type of 
app. 

Adding packaged apps 

You already saw how to add packaged apps to the simulator during our first app creation, but 
we're going to do a recap so I can show you what else is possible. 

To add a new packaged application click the Add Directory button on the Simulator Dashboard 

as shown in the screenshot below. 

85 http://ftp. mozilla.org/pub/mozilla.org/labs/r2d2b2g/r2d2b2g-5.0pre7-mac.xpi 
86 http://ftp.mozilla.org/pub/mozilla.org/labs/r2d2b2g/r2d2b2g-5.0pre7-linux.xpi 
87 http://ftp. mozilla.org/pub/mozilla.org/labs/r2d2b2g/r2d2b2g-5.0pre7- windows. xpi 
88 https://bugzilla.mozilla.org/ show_bug.cgi?id= 1001590 
89 https://developer. mozilla.org/en-US/docs/Tools/Firefox_OS_Simulator 



The Firefox OS Simulator 



56 



Dashboard Add Directory 



3 



ja|> 



[J Socket Test Packaged i 

C3 Las Click here to add packaqed 

Open Location rtrsere/soapdogruesKiprTesTemraSGSfciK 

vaiapps;:to the simulator 



o 



Memos Packaged App 
Last updated: 18 days ago 

Open Location /Users/soapdog/Dropbox/leanpub/firefoxos 
Validation Result: OK 



fx Imgur Image Uploader Packaged App 



Last updated: a month ago 
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Showing the Add Directory button that adds a packaged app to the simulator 



When you click on the button highlighted on the image, Firefox opens a file selection dialog. 
You should browse your hard drive and select the app manifest file for the application that you 
want to add to the simulator. If there are no issues with your manifest and your start file is ok, 
the application will be added and the simulator will launch with your app running. If there is 
anything wrong with your manifest, or some other issue, then an error report will be shown on 
the dashboard. 



Q MemOS Packaged App | 
Last updated: 25 days ago 
Open Location /Users/soapdog/memo/manifest.webapp 
Validation Result: INVALID (1 errors and 0 warnings) 
Errors: 

o Unknown permission ' stoge ' . 

Example of an invalid manifest 

Whenever you update your application you should click Refresh to update the version of the 
app on the simulator (you can also press CMD/CTRL+R on the simulator window to refresh). 



Adding hosted apps 

If you're building a hosted app then you should test it by using a web server. Do not try to use 
the method described above for hosted apps because you may miss some errors that will only 
happen on a hosted environment - such as serving the manifest with the wrong MIME type. Note 
that the simulator won't warn you about things like incorrect MIME types, but it's important to 
get such things right if you submit your app to the Mozilla Marketplace. 

Most of the hosted apps are not applications built exclusively for Firefox OS but responsive design 
based websites that are able to adapt themselves to different devices and resolutions. These web 
apps usually have a complex backend that needs to be in-place for the application to work and 
that's why you need to test the app using a real web server running your backend stuff. 
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To run your app in the simulator, fill the URL of your application in the text entry box on the 
top and click the Add URL button. 



Add Directory http://memos.andregarzia.com Add URL 



*W»e address - thet,rdick h * e " 

!D j^^Yg^^PdoS^esldop/teste/manifest.webapp Receipt. None 

esuti: ort 

ackaged App C Refresh > Connec 

Adding a hosted app to the simulator 

After clicking the button, the manifest is verified and if it is correct the application is added and 
the simulator is launched with your application running. Like when we're adding packaged apps, 
if something wrong happens with in the manifest you will see a report (e.g. "app submission to 
the marketplace needs at least an 128 icon"). 

As with packaged apps, whenever you update your application you should click Refresh to 
update the version of the app on the simulator (you can also press CMD/CTRL+R on the simulator 
window). 



Debugging 

After the application is added to the simulator we're able to debug it by clicking the Connect 
button next to the application listing on the dashboard. This will launch the simulator with your 
application running and the JavaScript Console open and connected to your app. 
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After pressing this button you will see a screen like this: 
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Developer Tools connected to the app running on the simulator 

With the tools connected to your app you can test your JavaScript, debug your DOM, edit styles, 
etc. Like those startup guys like to say: pivot until your app is good. 

Once your app is running well on the simulator it's time to test on a real device. 

Testing apps on a real device 

Nothing replaces testing on a real device. On the simulator, you test things by using a mouse and 
clicking on a computer screen; while on a real device you use your fingers on a touchscreen and 
by using physical buttons. Its a very different user and development experience. 

As an example why this type of testing matters, let me tell you a brief story: Some years ago, 
Raphael Eckhardt (the designer who created the cover of this book) and I were building a puzzle 
game not that disimilar to Bejeweled. Our game involved dragging and dropping some pieces on 
a board and was working pretty well on the simulator. 

When we then tested the game on an actual phone we realized our game components were not 
touch friendly at all: when placing a hand over the screen the board would vanish behind the 
hand. Even worst, the pieces the users were supposed to drag were smaller than the user's finger 
tip, so the user couldn't see what they were doing! In summary, our UX sucked very badly. That 
happened because we're kept trying things only on the simulator with a mouse that used a tiny 
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cursor. When we decided to try with our fatter-than-a-cursor fingers we realized that we need 
to rework our UI. 

To avoid having a similarly depressing experience, always test on a real device. . . or two, or more 
if you can get your hands on some. And test often with simple prototypes: otherwise, you can 
waste valuable time and money having to recreate assets. 

You can buy a developer preview phone running Firefox OS from the Geeksphone Shop 90 . I 
recommend using a Geeksphone Keon 91 because this device has similar specs to the devices that 
are being launched by Mozilla's partners. 

You can also buy a device targeted at consumers if you happen to live in one of the countries 
where they are already available. A third way is that you can replace Android with Firefox OS 
on some devices (some specific devices only, chance of bricking, don't blame me!) - but I don't 
recommend this unless you're a power user and like to spend a lot of time hacking. 



If you have a Firefox OS device (and have any needed drivers installed) then you can push apps 
directly from the simulator to the device if the device is connected to your computer. When the 
simulator detects that you plugged a Firefox OS phone, it will display a notice saying Device 
Connected. 



If your phone is connected (and detected) the simulator will add a new button next to Refresh 
and Connect called Push. When you press this button, a permission request dialog appears on 
the device screen asking for confirmation to install the pushed app. 



Connecting with a Firefox OS device 





□ 



Device connected. 



Device Connected! 



http://shop.geeksphone.com/ en/ 
91 http://www.geeksphone.com/ 
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Which button to press to push apps to the connected device 
And below we can see the permission request screen. 




Not the best picture in the world but shows the permission screen (sorry for the face it was 4:25 AM) 

With the application running on the device you can use remote debugging to connect a JavaScript 
console and debug the app. 



Summary 



In summary, the Firefox OS Simulator is awesome for building Firefox OS specific apps - but 
has some limitations if you are trying to build for a range of devices (e.g. currently, you can't 
emulate what Firefox OS would feel like on a tablet). 

Besides feeling awesome and empowered, by this point in the book you hopefully have a good 
grasp of the workflow for building apps for Firefox OS. 

In the next chapter we'll talk about the new app manager which is the new system that Mozilla 
is building to debug apps. It has more features than using just the Firefox OS Simulator. 



Distributing Your Apps 



Now that our application is ready we need to figure out a way to get it to our users. In the 
introduction chapter I mentioned that, unlike Apple, Mozilla does not force you to use their 
distribution channels - we're free to spread our creations as we wish. In this chapter we're going 
to learn how to distribute our app outside the Firefox Marketplace 92 . 

In my humble opinion, distributing your application outside the Mozilla Marketplace makes 
sense in the following two situations. 

1. You're developing an application for internal use within your company, or to a restrict- 
ed/limited group of users. If you ship it to the marketplace then it will be available to 
anyone and if you want to restrict the usage of the app to a group of people then you will 
need some kind of authentication scheme with a server backend or something similar. For 
example, when the Evernote application is launched for the first time, it asks the user to 
log in their servers. 

2. You already have a huge user-base that you can tap into for your app distribution. An 
example of this would be a news paper, like the Financial Times, which can simply 
distribute their app on their own website and reach most of their users. Remember that 
you can distribute your application outside the marketplace and in the marketplace at the 
same time, so if you already have your own marketing channel you can leverage that while 
still using the marketplace for reaching new users outside your own channel. 

The distribution process for hosted and packaged apps is similar, but it uses different functions. 
Thats why I'm discussing them separately. Regardless if your app is hosted or packaged, the 
workflow is usually the same: you provide a button or link on your own home page that says 
something similar to Click to Install Our App, or you use a special URL that when launched 
causes the installation routine to run. In both cases, a dialog is presented to the user asking him 
or her to confirm that they want to install the given app. 

Hosted Apps 



; http://marketplace. firefox. com 
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Code for hosted app installation 




In the sample above mani festURL contains the address for the manifest file. When this code runs, 
the system asks the user to confirm his desire to install the given application and depending on 
the choice of the user it runs the success or the error callback. 

To learn more about this API check the MDN page about application installation 93 . 



Packaged app installation is similar but instead of calling mozApps . i nsta 1 1 ( ) we call mozApps . i nsta 1 1 Package ( 
as shown in the sample code below. 

Code for packaged app installation 

1 // Absolute url to package: 

2 var packageURL = "http://myapp.example.com/myapp.zip"; 

3 var installapp = navigator .mozApps. installPackage(packageURL); 



This chapter discussed options for distributing applications outside of the Firefox Marketplace by 
using the installation and management APIs for Open Web Apps. There are many other routines 
available to do things such as checking if your application is installed (so that you can hide that 
Click Here To Install button). To learn more about those APIs check out the MDN page about 
application installation 94 (yes, gave you this link before - this time, click it! There is important 
stuff there). 

In the next chapter we're going to learn how to distribute our apps through the Firefox 
Marketplace. 



Packaged Apps 




Warning: I have the impression that packaged app installation outside of the market- 
place is not possible on Firefox OS version 1.0.1. Even though the API is documented, I 
have never tried it. Please if you try it, send me feedback so that I can update this book. 



Summary 



'https://developer.mozilla.org/docs/Apps/JavaScript_API 
'https://developer.mozilla.org/docs/Apps/JavaScript_API 
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Firefox Marketplace 

The Firefox Marketplace 95 is the online shop where you can buy or download applications for 
Firefox OS, Firefox, and Firefox For Android. This is the main channel for distributing Firefox 
OS applications, but you're not required to use it. If you want to distribute things outside the 
marketplace, read the previous chapter. 

To place your apps on the marketplace you need to be identified via Mozilla Persona 96 . Just click 
Sign Up and follow the instructions. Once you're identified, you will be ready to submit apps to 
the Firefox Marketplace. 



http://marketplace.firefox.com 
6 https://login. persona.org/about 
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Checklist before even thinking about sending an app 
to the marketplace 

All applications that are submitted to the marketplace go through an approval process (less 
scary than it sounds!). Hosted web applications go through a lighter process than privileged 
apps because they use less sensitive APIs. Before sending your application to the marketplace 
check out the marketplace review criteria 97 . The most important parts are (IMHO): 

• Firefox OS devices do not have a back button like Android and your desktop browser. If 
the user navigates to a screen inside your app where there is no way for them to get back 
to the previous place (i.e. the user gets stuck), your app will be rejected. 

• Your app should have a 60x60 icon and clear descriptions. 

• Your app should do what the description says. Saying one thing and providing something 
else will get your app rejected. 

• If your app asks for a given permission then you should use it somewhere in your code. 
Flagging your application as a privileged app and not using any privileged app API will 
cause your app to be rejected with a request that you submit again as a plain app. 

• Your application needs to have a privacy policy in place. 

• Manifest files should be served with the correct MIME type and come from the same 
domain as the app for hosted apps. 

There are other criteria discussed in the link above - and the rules can change without notice. 
It will be worth your time to read that page. Getting your application rejected because of small 
stuff that is easy to fix is a huge waste of time. Better get things right the first time (reviewers 
love to approve good apps!). 

Preparing your app for submission 

The steps required to submit your application to the marketplace are different depending on 
whether it's a hosted or a packaged app. For a hosted app, it just needs to be accessible on the 
Internet with the correct MIME type and manifest in place. Packaged apps need to be compressed 
using zip and deserve some extra attention. 

Many developers make the mistake of selecting the folder containing the application files and 
zipping it. This causes the zip file to contain a folder and this folder to contain the app. This 
is not the correct way to zip a Firefox OS application. The correct way is to zip the files and 
folders needed so that the manifest is on the root level of the zip file. On Mac OS X and Linux 
you can use the terminal to navigate to your application folder and use a command such as z i p 
-r myapp .zip * to compress things correctly as shown on the screenshot below. 

97 https://developer. mozilla.org/en-US/docs/Web/Apps/Publishing/Marketplace_review_criteria 
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Jidres-MocBook-Air:firefoxos-sanple-app-image-uploader soapdogS zip -r imgur.zip * 
adding: LICENSE (deflated 6750 
adding: README. md (deflated 58%) 
adding: app.js (deflated 6950 
adding: building_blocks/ (stored 056) 

adding: buUding_blocks/buUding_blocks.css (deflated 84*) 
adding: building_blocks/cross_browser.css (deflated 7856) 
adding: buiT.ding_bl.ocks/fonts/ (stored 056) 
adding: building_blocks/fonts/Fe_raSans-1.0/ (stored 030 

adding: building_blocks/fonts/FeuraSans-1.0/FeuraSans-Bold.woff (deflated 056) 
adding: building_bXocks/fonts/FeuraSans-1.0/FeuraSans-Light.i«off (deflated 050 
adding: building_blocks/fonts/FeuraSans-l.0/FeuraSans-Medium.woff (deflated 050 
adding: buildingj3locks/fonts/FeuraSans-1.0/FeuraSans-Regular.woff (deflated 056) 
adding: building_blocks/fonts/FeuraSans-1.0/LICENSE (deflated 3656) 
adding: building_blocks/ fonts. ess (deflated 8556) 



Correctly zipping the files 



This zip file is what we send to the marketplace. 



Submitting your app to the marketplace 

Now with your application ready, and with the firm knowledge that it meets the review criteria, 
its time we send it to the marketplace. To do so browse to My Submissions using the gear button 
on the top of the marketplace page. 



O 





andre@andregarzia.com 
Edit Account Settings 






My Apps 












Feedback 




> 


Sign Out 









My Submissions 

Inside the application management page, you need to click on Submit An App on the top menu. 



PAYMENT KEYS SUBMIT A NEW APP 

Kinda Obvious 

Submit An App 

This link will lead you to the form for submitting new apps, as seen in the screenshot below. 



The Firefox Marketplace 

Submit an App 



Free 



© © 

Agreement Submit 

Paid / ln-app 




Firefox OS 
Fully open mobile ecosystem 

0 



i 


s 






Firefox 




Windows, Mac and 


Linux 


Q 



0 



Firefox Mobile 

Android smartphones 




□ 



Firefox Tablet 
Android tablets 

Q 



Hosted 


Packaged 


M Select a file... 1 




Your packaged app should end with .zip. 





Submit New App 
On this screen you will select the following options: 

• If the application is hosted or packaged. 

• If it is free or paid (or uses in-app purchases). 

• What type of devices it is available for (Firefox OS, Firefox Desktop, Firefox for Mobile on 
phones, Firefox for Mobile on Tablets). 



After making these choices you're driven to the second screen. On this book we're focusing on 
packaged apps but hosted apps are similar. 

In the remaining text of this chapter we're assuming that we're shipping a free Firefox OS 
packaged app. In this case we need to upload the zip file we prepared on the previous section. 

After uploading the file, it undergoes an automated process and a report is shown with many 
options. 
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Hosted Packaged 



Select a file.. 



Your packaged app should end with . zip. 
Finished validating imgur.zip 



100% complete ■ 683.83 KB of 683.83 KB 

^ Your app passed validation with no errors and 6 warnings. 

See full validation report 



App Minimum Requirements 

Check the boxes of the features that your app requires to function properly. Your app will be hidden from users whose devices don't support it. 



Network Information [navigator.mozConnection | [ navigator.inozHobileConnection | 

The app requires the ability to ge; information about the network connection (the ' navigator.mozConnection ' API). 

l3 Smartphone-Sized Displays (qHD) 

The app requires the platform to have a smartphone-sized display (having qHD resolution). This option indicates that the app will be unusable on larger displays (e.g., 
tablets, desktop, large or high-DPI phones). 



l3 Web Activities | HozActivity | 

The app requires Web Activities (the MozActivity' API). 

After the zip upload 

From the screen shot above we can see that the app I sent to the marketplace has no errors 
but contains six warnings. Ignoring the warnings for the sake of this text, lets check what the 
minimum requirements for this app are. In this case, the last option Smartphone-Sized Displays 
(qHD) should be unchecked because our application adapts to any screen size. 

The next step is called Step #3: Details and it is where you fill the information about your 
application such as category, description, screen captures, etc. 
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♦ » Developers » My Submissions » Imgur Image Uploader » Submit App 

Submit an App © © © 

Agreement Submit Details 

Edit App Details 

Please review your listing information below. We've pre-filled as much as we can from your manifest. 



Imgur Image Uploader 

https://marketplace.firefox.com/.../ imgur-image-uploader-1 Open details page 
Edit 



Description: * 



An app to share images using the imgur service 



This description will appear on the details page. 



Categories: * Pick one or two categories. 

Entertainment Productivity 

Business 0 Social 
Games Travel 
Music Books 



Health 8. Fitness 
Lifestyle 
(3 Photo & Video 
Utilities 



Sports 
Reference 
Maps & Naviga 



Filling details 

After filling-in the details, the submission process is done. Now you just wait for the approval 
from the marketplace reviewers. Congratulations you shipped a Firefox OS application!!! 

On the Application Management page 98 you can check the status of your submissions and alter 
details if needed. 

To learn more about submitting applications to the Firefox Marketplace read this article on the 
Firefox OS developer hub". 



Summary 



Congratulations!!! You have a new application on the Firefox Marketplace, you're exploring a 
brand new market! 

I hope you enjoyed this quick guide. I plan to update and expand this guide often - so keep your 
eyes open and register for the updates. If you downloaded this book from Leanpub then its all 
good because you will receive emails about any updates. If you downloaded it from somewhere 
else then please consider fetching it from the official page at Leanpub 100 and registering your 
email. It's free and, no, you won't get any spam. Promise. 



https://marketplace.firefox.com/developers/submissions 
"https://marketplace.firefox.com/developers/docs/submission 
100 http://leanpub.com/quickguidefirefoxosdevelopment 
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Please send me feedback. This book was written by pulling all-nights before a tech confer- 
ence so you can infer how much I enjoy this project and want to see it succeed. I can be 
reached for feedback on my Twitter account at @soapdog 101 and over email at fxosquick- 
guide@andregarzia.com 102 . My home page is at http://andregarzia.com 103 . 

Now that you're a part of the group of Firefox OS app creators, come be a part of the greater 
Mozilla community: Help keep the web free and open made by users for users. Join us at 
http://www.mozilla.org/contribute/ 104 and help Firefox OS grow! 



'httpV/twitter.com/soapdog 
2 mailto:fxosquickguide@andregarzia.com 
' 3 http://andregarzia.com 
' 4 http://www.mozilla.org/en- US/contribute/ 



Appendix 1: Useful links 

• Mozilla 105 

• Mozilla Brasil Community Page 106 

• Firefox OS Developer Hub 107 

• Mozilla Developers Network 108 : Best documentation ever! 

• Firefox OS 109 

• WebAPI on Mozilla Wiki 1 10 



'http://mozilla.org 

'http://mozillabrasi.org.br 

http://marketplace.firefox.com/developers 

'http://developer.mozilla.org/ 

'http://www.mozilla.org/pt-BR/firefox/os/ 

'http://wiki.mozilla.org/WebAPI 



